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Appendix A 

A. Example XML Documents 

Below are example instances of each document type: 

B. Init 

The "init" document contains the name of the application and a human readable description. 
<?xml version="1.0" ?> 

<xamini t xml ns="http: //www. e-speak. net/ schema/XAM/i ni t"> 

<serviceName>virtual File system:version 3.3</serviceName> 

<servi celnstanceldenti fier>iPl5 . 144 . 65 . 2 : pi d=432</servi celnstanceldenti fi er> 

</xamlm't> 

C Request 

The "request" document details what is required. 

<?xml version="1.0"?> 

<xamRequest xml ns="http: //www. e-speak. net/schema/XAM/request" > 

<i nf ormati onModel>typeCatal og</ i nf ormati onMode"! > 
<i nf ormati onModel >conf i gurati onLi st</i nf ormati onModel > 
<i nf o rmati onwodel >systemvari abl es</i nf ormati onModel > 
</xamRequest> 
Details 



The "details" document describes the current model state. 
<?xm1 version="1.0"?> 

tai 1 s xml ns="http : //www. e-speak. net/schema/XAM/detai 1 s"> 
<systemvari abl es> 

<!-- enable content is a boolean java object — > 
<enable>true</enable> 

<serviceldentifier>2nd Virtual File Systetti:version 3.2</serviceldentifier; 
<se rvi celnstanceldenti f i er>2nd IP15 . 144 . 65 . 2</se rvi celnstanceldenti f i er> 
<clockResol uti on>2nd 0 . 015</clockResol ution> 

<! — minReportinterval content must be a long java object — > 

<mi nReportlnterval>55555</minReportInterval> 
</systemVari abl es> 
<typeCatalog> 

<transaction> 

<! — Order of elements within any container — > 
<!-- is not garunteed --> 
<typeidenti fi er>Download_f il e</typeldenti fi er> 
<description> file downloaded from the service</description> 

<vari abl espeo 

<name>2nd Fi 1 e_naine</name> 
<c1 ass>stri ng</d ass> 
<key>true</key> 
</variablespec> 
<vari ableSpeo 

<name>2nd size</name> 
<key>f al se</key> 
<cl ass>stri ng</c! ass> 
<unit>2nd bytes</unit> 
</variableSpec> 
<vari ableSpeo 

<name>2nd size</name> 
<key>fa1 se</key> 
<cl ass^stri ng</cl ass> 

<!-- unit is optional — > 
<unit>2nd bytes</unit> 

<!— description is optional — > 
<description>sampl i ng f rame</descri ption> 
</vari abl espeo 
<vari abl espeo 

<name>Fi 1 e_name</name> 

<!-- element "class" content must be "string" since --> 
<cl ass>stri ng</cl ass> 

<!— key is optional, key content must be boolean --> 
<key>f al se</key> 
<alphabet> 

<enum>lst appl e</enum> 
<enum>lst orange</enum> 
</alphabet> 

<unit>transaction i nterval </unit> 
<descri pti on>sainpl i ng f rame</descri pti on> 
</vari ableSpeo 
<vari ableSpeo 

<name>2nd aLongKeyVar</name> 
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<!— "class" content r 

<! — element range i: 
<cl ass>l ong</cl ass> 
<key>true</key> 
<alphabet> 

<range>2nd 0. . 100</range> 

<range>2nd 200. .i</range> 
</al phabet> 

<unit>2nd percent</um't> 

<description>2nd (B.) no bugs </descriptio 
ri ableSpeo 



<vari abl espeo 

<name>2nd aLongKeyVar</name> 
<cl ass>l ong</c I ass> 
<key>true</key> 
<alphabet> 

<range>2nd 0. .100</range> 

<range>2nd 200. .i</range> 
</al phabet> 

<unit>2nd percent</um"t> 

<description>size the file downloaded</descri ption> 
</vari abl espeo 
<van' ableSpeo 

<name>2nd aLongKeyVar</name> 

<class>long</class> 

<key>t rue</key> 

<al phabet> 

<range>2nd 0. . 100</range> 
<range>2nd 200. . i</range> 

</alphabet> 

<unit>2nd percent</unit> 

<description>2nd (B.) no bugs </description> 
</vari abl espeo 
<vari ableSpeo 

<name>2nd File_name</name> 

<cl ass>stri ng</cl ass> 

<key>true</key> 
</vari abl espeo 



<van" abl espeo 

<name>2nd File_name</name> 

<class>string</class> 

<key>true</key> 
</vari ableSpeo 
<vari abl espeo 

<name>2nd astri ngKeyvar</name> 

<class>string</class> 

<key>true</key> 

<alphabet> 

<!-- Content must be unique — > 
<enum>appl el</enum> 
<enum>orangel</enum> 
<enum>appl e2</ enum> 
<enum>orange2</enum> 
</alphabet> 

<unit>2nd percent</unit> 

<description>2nd the user utilizing the disk</descriptic 
</vari abl espeo 
<vari abl espeo 

<name>2nd astri ngvar</name> 

<class>stnng</class> 

<key>f al se</key> 

<al phabet> 

<enum>apple</enum> 
<enum>orange</enum> 

</alphabet> 

<uni t>percent</um" t> 

<description>the user utilizing the disk</description> 
</vari ableSpeo 
<vari ableSpeo 

<name>2nd aLonqKeyVar</name> 

<class>long</class> 

<key>t rue</key> 

<al phabet> 
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<! — Content must be unique — > 
<range>0. .100</range> 
<range>200 . . i </range> 
<range>400. .450</range> 
<range>2nd 200. .i</range> 
<range>0, .101</range> 
<range>2rd 200 . . i </range> 
</al phabet> 

<unit>2nd percent</unit> 

<description>2nd (B.) No BUGS </description> 
</variableSpec> 

<typeldenti fi er>2nd testTransaction : sum: aLongVar</typeldenti f l e 
<deri vedTypeidenti f i er>2nd testTransacti on</deri vedTypeidenti f i < 
<den" vedvari abl eName>2nd aLongvar</deri vedvari abl eName> 

c <t yp eIdent ^ ier>testAtomi - c< ^ t y peIc j ent ^f 1 - er> 
<description>a test atomi c</descri ption> 
<variablespec> 

<name>astn" ngvar</name> 
<cl ass>stri ng</cl ass> 
<key>fal se</key> 
<al phabet> 

<e num>app1 e</e num> 
<enum>orange</enum> 
</alphabet> 
<unit>percent</unit> 

<description>the user utilizing the disk</descnption> 
</variableSpec> 
</atomi c> 

<poll> 

<typeldenti f i er>testPo1 1 i ng</typeidenti f i er> 
<descn"ption>a Polling test</description> 

<pol 1 <t yp eIc j e nti f i er>testPol 1 </typeidenti f i er> 

<description>a bigger poll test </description> 
<variablespec> 

<name>aStri ngvar</name> 
<cl ass>stri ng</cl ass> 
<key>f al se</key> 
<al phabet> 

<enum>pol 1 ed_appl es</enum> 
<enum>pol 1 ed_oranges</enum> 
</al phabet> 
<unit>percent</uni t> 

<description>the user polling a service</descri ption> 
</variable5pec> 

</poll> 

<! — threshold not shown here: — > 
<!-- group not shown here: --> 
</typeCatal og> 

<configList xmlns="http://www. e-speak.net/schema/XAM/configure > 

<SUm> <handle>2888hfshgfh-sd/handle> 

<typeldentifier>test sum: Du rati on</typeldenti fi er> 
<aggregationlnterval >20000.0</aggregationlnterval> 

</sum> 

<sum> <handl e>2 888888888888</handl e> 

<typeidenti f i er>test sum : du rati on</typeidenti f i er> 
<aggregati onlnterval >20000 . 0</aggregationlnterval > 

</sum> 

<handl e>2999999999999</handl e> 
<typeldentifier>2nd sum </typeidenti fier> 
<aggregati onlnte rval >200 . 0</agg regati onlnte rval > 

<transaction> 

<handl e>100</handl e> 

<typeldenti f i e r>Tran_2</ty peidenti f i e r> 
<restriction> TRUE </restri ction> 
</transaction> 
<poll> 

<handl e>2</handl e> 

<typeldentifier>Poll_2</typeldenti fier> 
<canbacklnterval>2</callbackinterval> 

</poll> 

<handle>22</handle> 
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<typeldenti f i er>Secu ri ty_Authori zation_f ai 1 ure</typelder 
<restriction> False </restriction> 

</atomi c> 
<poll> 

<handl e>3</handl e> 

<typeldenti f i e r>Pol 1 _3</typeidenti f i e r> 
<cal 1 backlnterval >3</cal 1 backlnterval > 

</poll> 
</configList> 
</xamdetail s> 

Configure 



The "configure" document details the settings which the XAM library should use. 

<?xml version="1.0"?> , , , 

<xamconf i gu re xml ns="http : //www. e-speak . net/schema/XAM/confi gure > 
<systemvari abl es> 

<enable>true</enable> 

<minReportinterval>15</minReportinterval> 
</systemvari abl es> 
<configList> 

<transaction> 

<handle>l</handle> 
</transaction> 
<transaction> 

<handle>2</handle> 
</transaction> 
<transaction> 

<handl e>l</handl e> 

<1 — optional element — > 
<typeldenti fi er>DownLoad_f i le</typeldenti fi er> 
</transacti on> 

^rndle: 

<transaction> 

<handle>100</handle> 

<typeidenti fi er>Tran_2</typeidenti fier> 
<restriction> TRUE </restriction> 
</transaction> 
<transaction> 
<handl e>101</handl e> 

<typeldenti f i er>Tran_2</typeldenti f i er> 
<! — optional element --> 
<restriction> TRUE </restri cti on> 
</transaction> 
<transaction> 

<hand1e>102</handle> 
<restriction> true </restriction> 
</transaction> 
<atomi c> 

<handle>l</handle> 

<! — Optional Element — > 
<ty pelde nti f i e r>Secu ri ty_Authori zati on_f ai 1 u re</typelder 

<atomi c> 

<handl e>l</handl e> 
</atomi c> 
<poll> 

<handle>l</handle> 

<! — Optional Element — > 
<typeidenti f i er>Pol l_l</typeidenti f i er> 
-' — optional Eler"" 1- — 
:rval>l</cal'' 
Optional El'. 
• False </restriction> 

</poll> 
<poll> 

<handle>l</handl e> 

</poll> 
<count> 

<handl e>3</handl e> 

<typeidentifier>Download_file-count</typeldentifTer> 

<!— Must be a float --> 
<aggregationlnterval>15.0</aggregationinterval> 

<! — optional Element — > 
<topNSi ze>10</topNSi ze> 

<!-- optional Element 0...n, Content MUST be unique - 
<restriction> TRUE </restri ction> 
<col 1 apseDi mensi on>Fi 1 e_ty pel</ col 1 apseDi mensi on> 
<col 1 apseDi mensi on>Fi 1 e_ty pe2</ col 1 apseDi mensi on> 
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<col 1 apseDimension>Fi 1 e_type3</col 1 apseDi mensi on> 
<col 1 apseDi mensi on>Fi 1 e_type4</col 1 apseDi mensi on> 
<col 1 apseDimensi on>Fi 1 e_type5</col 1 apseDimensi on> 
<coll apseDitnensi on>mvoker_lDl</coll apseDi mensi on> 
<col 1 apseDi mensi on>lnvoke r_lD2</col 1 apseDi mensi on> 
<restriction> fail </restriction> 
<col 1 apseDi mensi on>mvoker_iD3</coll apseDi mensi on> 
<col 1 apseDi mensi on>Invoke r_ID4</col 1 apseDi mensi on> 
</count> 

<handle>3</handle> 

<typeldenti f i er>Count_2</typeldenti fi er> 
<aggregati oninte rval >150 . l</agg regati oninterval > 

<handle>4</handle> 

<! — Optional Element — > 
<typeldenti fier>SumType</typeldenti f i er> 

<! — Must be a float --> 
<aggregationmterval>20000.00001</aggregationinterval> 

<! — optional Element --> 
<topNSi ze>9</topNSi ze> 

<!— optional 0...n element(s), content MUST be unique— 
<col 1 apseDi men si on>col 1 _Di m_l</col 1 apseDi men si on> 
<restriction> true </restriction> 
<col 1 apseDi mensi on>Coll_Di m_2</col 1 apseDi mensi on> 
<restriction> false </restriction> 
<col 1 apseDi mensi on>Col 1 _Di m_3</col 1 apseDi mensi on> 
<col 1 apseDi mensi on>Col 1 _Di m_4</col 1 apseDi mensi on> 

<handl e>4</handl e> 

<typeidentifier>SumType_2</typeidentifier> 
<agg regati oninte rval >200 . 0</agg regati oninte rval > 

<threshol d> 

<handl e>5</handl e> 

<! — optional Element — > 
<restriction> TRUE </restriction> 

<! — optional Element — > 
<typeidenti f i er>ThreshType</typeldenti f i er> 

<!-- Must be a float --> 
<aggregati oninterval >1. 02 5</aggregati oninterval > 

<!-- Optional Element — > 
<topNSi ze>ll</topNSi ze> 

<!-- optional 0..n el ement(s) , cont 
<col 1 apseDi me nsi on>Col 1_Di m_l</col 1 apseDi mi 
<col 1 apseDi mensi on>Col 1 _Di m_2 </col 1 apseDi Bo.= n 
<col 1 apseDi mensi on>Col l_Di m_3</col 1 apseDi mensi o, 

<! — Must be a float --> 
<threshol dval ue>30 . 0</threshol dval ue> 
</threshold> 
<threshold> 

<handle>50</handl e> 

<agg regati oninte rval >102 50 . 0</agg regati oninte rval > 
<thresholdvalue>300.0</thresholdvalue> 
</threshold> 
</configList> 
</xamconfigure> 
F Report 

The "report" document contains the measurement results. Several periods may be combined 

in one documents. 
<?xtnl version="1.0"?> 

<xamReport xmlns="http://www.e-speak.net/schema/XAM/report > 
<ti meBase>2000-04-18Tl7 :43 : 30 . 140-08 : 00</ti meBase> 
<reportmterval>2nd 1. 313</reportInterval> 

<!— a bundle should contain only one repetitive sibling element. — > 
<bundle> 

<handl e>100</handl e> 

<typeidentifier>testPollData_100</typeldentifier> 
<pollData> 

<!-- content in Name Elemant must be unique — > 
<!-- OR Content in value element must be unique — > 
<vari abl eval ue> 

<name>astrinqvarl</name> 
<value>long in the toothl</value> 
</vari abl eval ue> 
</pollData> 
<pollData> 
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<variablevalue> 

<name>astri ngvar2</name> 
<value>long in the toothl</value> 
</variablevalue> 

</pollData> 
<poll Data> 

<vari abl eval ue> 

<name>astri ngvarl</name> 
<value>long in the tooth2</val ue> 
</vari abl eval ue> 
</pollData> 
<pol 1 Data> 

<vari abl eval ue> 

<name>astri ngvar2</ name> 
<value>1ong in the tooth2</value> 
</vari abl eval ue> 
</pollData> 
<pol 1 Data> 

<!-- other instance data here — > 
</pollData> 

<!— other instance data here — > 
</bundl e> 
<bundle> 

<handle>2nd 2</handle> 

<typeldenti f i er>2nd testTransacti on</typeidenti fi er> 
<transactionData> 

<!-- Element Content must be unique --> 
<i nstancelD>l</i nstanceID> 

<!— optional Element — > 
<parentCor rel ator>2nd nul 1 </ parentcorrel ator> 
<ti meBase>2nd 2000-04-18T17 : 43 : 30 . 250-08 : 00</ti meBase> 
<duration>2nd 0. ll</duration> 

<status> 2nd The status is still very good today .,. </■ 
<! — content in Name Elemant must be unique --> 

<vari abl eval ue> 

<name>astri nqvarl</name> 

<value>long in the tooth stri ngl</value> 

</vari abl eval ue> 

<vari abl eval ue> 

<name>astri ngvarl</name> 

<value>2nd long in the tooth string2</value> 
</vari abl eval ue> 
<vari ableValue> 

<name>astri ngvar2</name> 

<value>long in the tooth stri ngl</value> 
</vari abl eval ue> 
<vari abl eval ue> 

<name>astringvar2</name> 

<value>2nd long in the tooth stri ng2</val ue> 
</vari abl eval ue> 
<variabl eValue> 

<naine>2nd aLongVar</name> 

<value>2nd 82</value> 
</vari abl eval ue> 
<vari abl eval ue> 

<name>2nd aLongKeyVar</name> 

<value>2nd 83</value> 
</vari abl eval ue> 
<vari abl eval ue> 

<n ame> 2 nd aDou bl evar</name> 

<value>2nd 86.1459</value> 
</vari abl eval ue> 
</transacti onData> 



<i nstancelD>2</i nstanceiD> 

<ti meBase>2000-04-18Tl7 : 43 : 30 .250-08 : 00</ti meBase> 
<du rati on>0 . ll</du rati on> 

<status>The status is still very good today .,. </status> 
<vari abl eval ue> 

<name>astri ngvarl</name> 
<value>long in the tooth stringl</value> 
</vari abl eval ue> 
</transactionData> 
:ionData> 
<i nstancelD>3</i nstancelD> 

<ti meBase>2nd 2000-04-18T17 : 43 : 30 . 2 50-08 : 00</ti meBase> 
<duration>2nd 0.11</duration> 

<status> 2nd The status is still very good today .,. </stz 
<vari abl eval ue> 

<name>aStri nqvarl</name> 
<value>long in the tooth stri ngl</value> 
</vari abl eval ue> 
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</transactionData> 
</bundle> 
<bundle> 

<handle>2nd l</handle> 

<typeidentifier>2nd testAtomic</typeidentifi er> 
<atomi cData> 

<!-- elment is optional — > 
<parentcorrelator>2nd test r</parentCorrelator> 
<ti me Base>2nd 2000-04-18T17 : 43 : 30 . 250-08 : 00</ti meBase> 
<vari abl eval ue> 

<name>2nd aStri ngVar</name> 

<value>2nd long in the tooth</value> 
</vari abl eval ue> 
<vari abl eval ue> 

<name>2nd aStri ngKeyVar</name> 

<value>2nd long in the tooth with a key hole</val 
</vari abl eval ue> 
<variabl evalue> 

<name>2nd aLongVar</name> 

<value>2nd 1111111122222222233333333</val ue> 
</vari abl eval ue> 
<vari abl eval ue> 

<name>2nd aLongKeyVar</name> 

<va! ue>2nd 88884444422222</val ue> 
</vari abl eval ue> 
<vari abl eval ue> 

<name>2nd aDoubleVar</name> 

<value>2nd 87.1459</value> 
</vari abl eval ue> 
</atomicData> 

<at ° miCD < a ri a meBase>2nd 2000-04-18Tl7:43:30.250-08:00</timeBase> 
<vari abl eval ue> 

<name>2nd aStri ngvar</name> 
<value>2nd long in the tooth</value> 
</vari abl eval ue> 
</atomi cData> 

<atoini cD < a t 1 ^ a m > eBase>2nd 2001-04-18T17 : 43 : 30 . 2 50-08 : 00</ti meBase> 
<vari abl eval ue> 
<natne>2nd aStri ngvar</name> 

<value>2nd long in the tooth</value> 
</van* abl eval ue> 

<!— other instance data here — > 
</atomi cData> 

<! — other instance data here --> 
<bundle> 

<handle>6</handle> . 

<typeidenti f i e r>te stTransacti on : sum : Du rati on</ty peidenti ti er> 
<sumData> 

<ti meBase>2000-04-18Tl7 : 43 : 28 . 500-08 : 00</ti meBase> 
<agg reqati onlnte rval >nul 1 </agg regati oninte rval > 
<Ex>2.0620000000000003</Ex> 
<EX2>0 . 24450000000000002</Ex2> 
<N>18.0</N> 
<Max>0.203</Max> 
<Mi n>0 . 109</Mi n> 
</sumData> 

<SUmData <timeBase>2000-04-18Tl7 : 43 : 28 . 500-08 : 01</ti meBase> 

<aggregationlnterval>null</aggregationinterval> 

<EX>2 .0620000000000003</EX> 

<Ex2>0 . 24450000000000002</Ex2> 

<N>18.0</N> 

<Max>0.203</Max> 

<Mi n>0 . 109</Mi n> 
</ sumData> 
</bundle> 
<bundle> 

<!-- handle context must be unique — > 
<handl e>3</handl e> 

<typeldenti f i er>testAtomi c: count</typeidenti ti er> 

<COUntDa < t ti > meBase>2000-04-18Tl7 : 43 : 2 8 .484-08 : 00</ti meBase> 
<aggregati oninterval >nul 1 </aggregati oninterval> 
<count>18</count> 
</countData> 
</bundle> 
<bundle> 

<handle>4</handle> 

<typeldenti f i er>testAtomi c : count</typeldenti fi er> 
<countData> 
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<ti meBase>2000-04-18Tl7 :43 : 28 . 484-08: 00</ti meBase> 
<agg regati oninte r val >null </aggregati oninte rval > 
<count>18</count> 
</countData> 

<countData> , . 

<ti meBase>2000-04-18Tl7 : 43 : 28 . 484-08 : 00</ti meBase> 
<agg regati onlnterval >nul 1 </aggregationInterval > 
<!-- count content must be unique if everything els( 
<count>19</count> 
</countData> 
</bundle> 

<!— not shown here: Count with TopN_ — > 

<! — not shown here: Group with or without TopN — > 

<i-- not shown here: Sum with or without TopN --> 

<!— not shown here: Threshold with or without TopN --> 

</xamReport> 

Clos 



The "close" document contains a description of the closure reason or nothing. If either the 
XAM enabled application or the XAM service receives a close message they should reply 
with another close message and cease further communication. If either party has send a close 
message they should not send further close messages upon receipt of a close message. 

<?xml version="1.0"?> 

<xamClose xmlns="http://www. espeak.org/XAM/close > 

</xamclose> 

H. Mo 

The "info" document contains some information that is outside the scope of measurements. 
For example if an error occurs then an info message could be sent indicating what happened 
and what action has been taken. Implementations should be more tolerant of info messages 
containing unexpected element that they may be for other documents. 

<?xml version="1.0"?> 

<xaminfo xmlns="http: //www. espeak.org/XAM/mfo > 
<badDocument> 

<documentName>xamConfig</do< 
<status>ignored</status> 
<reason>invalid xml</r€ 
</badDocument> 
</xaminfo> 

I Schemas 



Example Java usage 
test.iava 



* This is a example program which uses the xam interface, 
public class test implements XAMCallbackinterface { 



public static void main(String[] args) { 
system. out. print! n ("XAM test running"); 
XAMTime time = XAMClock.getTimeO ; 

System. out. println ("The time is:" + time.getlSO860lFormatQ) ; 



y testQ; 



t.theMain(args) ; 

} 
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* the instance main 

* Sparam args command line arguments 

void theMain(String[] args) { . ,..,„„ 

XAMSession s = XAMFactory. createSessi on( test application vl.O , 



ory.creai 

"15 . 144 . 69 . 2 51: pi d=12 312 ") ; 

iDoubl eva 
i Line the dibiN »„.»j uujj j, 

:reatei_ongvariableSpec("Disk", true, new string [] { l..i }, null, 



// disk_utilization example 

XAMVariableSpec du[] = { . r „„ „„„„, 

s.createDoublevariablespecC'utilization", newstrmg[] {"0..100"} 
"percent", "the ammount of time the disk^was bu sy^'.) 

"the disk being used"), 

s.createstri ngvariableSpecC user , true, null, null, 
"the user utilizing the disk") 

XAMPollType diskutilization = 

s.newPollMeasurementTypeC"Disk_utilization , du, this); 

diskutilization. setDescri ption("the percentage of the time a disk was being utilized 
by a user") ; 

// Download file example 

XAMVariableSpec df[] = { . 
s.createstri ngvari abl eSpec("File_name , false, The name of the tile being 
downloaded"), „ „ , ,_ , ... , . 

s.createstri ngvari abl eSpec(File_type, true, The type of the file being 

downloaded ^_ create| _ on g V ariableSpecC"size", false, "the size of the file being downloaded"), 
s . createstn ngvari abl espec ("lnvoker_iD" , t rue , 

"the user utilizing the disk") 

XAMTransacti onType downloadFile = 

s. newTransactionType("Download„file" , df) ; 

downloadFile. setDescri ption("a file download from the file server"); 



address") , 



// Security_Authorization_failure example 
•••■lvariablespec saf[] = { 

s.createStringVariableSpec("Conversation_type , true, The XMI conver: 



s.createStringVariableSpec("Document_type", true, "The XML document schema 

s . createStri ngvari abl espec ("lnvoker_iD" , t r 
s . createStri ngvari abl espec ("Reci pi ent_lD" , 
s . createStri ngvari ableSpec("Reason_stri ng" , 



, it)7 



dwnl dfi leinstance . setstri ngval ue(" Fi 1 e_name" , 



// ... download the file here 



;e (" invoke r_iD", "guest"); 



= ai = securityAuthFail .getinstanceO ; 

safai .setStringvalueC'Conversation_type", 

"http://www.espeak.net/conversations/fdsds.xml ) ; 
safai .setstri ngval ue C'Document_type ', 

"http://www. espeak . net/documents/f saasfdsds . xm I ) ; 
safai .setstri ngval ue("invoker_iD", 

"PK:SHA-l:f34Dff23rd32tre5fFG445rFrr"); 
safai. setstri ngval ue ("Reci pi ent_iD", 

"PK:SHA-l:DFsdsfHeRe85F4g55ggyh6h6v5b ) ; 
safai .setstri ngvalue("Reason_String", 

"auth fail code 42 (the certificate was corrupt)'); 

safai . reportQ ; 
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' The call back method is in this example implemented by the application objec 
' Oparam measurementlnstance 

iblic void requestingMeasurement(XAMPollinstance measurementlnstance) { 
double utilization[][] = { 
{ 34, 56, 45, 45, 56 
} ' { 45, 36, 35, 15, 76 

} ' { 39, 26, 32, 45, 56 
} 

String user[] = { 

"torn", "dick , harry 

long diskNum[] = { 

11, 12, 13, 14, 15 

}; 

for (int u = 0; u < user. length; u++) { 

measurementlnstance. setstn nqval ue( 'user user[u])-, 
for (int d = 0; d < diskNum. length; d++) { 

measurementlnstance. setLongvalueC disk , _diskNum[d]) ; 
rneasu rementlnstance . setDoubl eval ue ("Uti 1 i zati on , 
utilization[u][d]); 



2. XAM Java API 

The following Java API is a first draft for the Java XAM application library. 

3, XAMFactorv. iava 

/*$id: XAMFactory.java,v 1.1.2.4 2000/05/12 14:32:30 olima Exp $*/ 



* (c) copyright 2000 Hewlett-Packard company ^ 

* This program is free software; you can redistribute it and/or modify it * 

* under the terms of the GNU Lesser General public License as published by - 

* the Free Software Foundation; either version 2.1 of the License, or ; 

* (at your option) any later version. ' 

* This proqram is distributed in the hope that it will be useful, but 

* without ANY WARRANTY; without even the implied warranty of merchantability ; 

* or fitness for A particular purpose. See the gnu Lesser General Public • 

* License for more details. [, 

* You should have received a copy of the GNU Lesser General Public License 

* along with this program; if not, write to the Free Software Foundation, ; 

* inc., 675 Mass Ave, Cambridge, MA 02139, USA. ; 



* This class is a factory for instances of XAMSession the factory may return 

* different types of XAMSession depending on the system propertie 

* "xam. implementation. class". The default implementation returned 

* is <code>net.espeak. management. xam. noop . NoopSessi on<code> 

* ©author David Stephenson 

* ©version SRevision: 1.1.2.4 $ SDate: 2000/05/12 14:32:30 $ 
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public class XAMFactory { 



; static XAMSes: 



; whether the session object in <code>latestsession</code> is named or not. 
:ic boolean sessi onlsNamed = false; 



■ The system property that holds the name of the implemem 

ic static final Strit 
"XAM .imp! ementati on . < 



; The default noop imp! i 



* The actual implementation class. 

public static final Class theXAMlmplei 
1 oadof XAMltnpl ementati on () ; 



* The default noop impl 
public static final String default_xam_implementation_name = 

DEFAULT__XAM_IMPLEMENTATION_CLASS . getName O I 

^* The default noop implementation class name. 

public static final string xam_loadfailexit_property = 
"XAM . i mpl ementati on . 1 oadexi t" ; 

/ * The default class load failure for the XAM implementation. 

* If true the library will call <code>System. exit(l) ;</code> 

public static final String default_xam_LOADFAILEXIT = "false"; 



i XAMSession instance. This should generally be called 



K => application instance. 

* ©param ApplicationversionName an identifier for the application 

* Iparam ApplicationinstanceName an identifier for the application 

* instance. No other application or service of with the same 

* ApplicationversionName should have the same ApplicationinstanceName. 

* ©throws classNotFoundException this exception may be thrown if the xam 

* implementaion cannot be loaded. 

public static synchronized XAMSession createsession(String applicationVersionName, 
String appli cationlnstanceName) { 

// check that the application has supplied 
// some application names with content 
if (applicationVersionName == null 

|| applicationVersionName. equalsC"")) { 

throw new XAMExceptionC'The ApplicationversionName cannot be empty ); 
.- ==null 
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throw new XAMExceptionC'The ApplicationinstanceName cannot be empty"); 

} 

// check if we al rady have a session created but without any 
// application names or we don't have a session yet. 
if (sessionlsNamed == true II latestsession == null) { 

// we already had a named session so create a new one for the new name: 
// or we don't have a session yet. 
latestsession = createSessi onobjectO ; 

} 

l named session 

// now put the application names into the session. 

1 atestsessi on . setAppl i cati onNames (appl i cati onversi onName , 

appl i cati onlnstanceName) ; 
return latestsession; 



* create a XAMSession instance. This should generally be called 

* once per application instance. The Application instance will be 

* randomally generated. 

* @param Appl i cati onversi onName an identifier for the application 

* |throws S ClassNotFoundException this exception may be thrown if the XAM 

* implementaion cannot be loaded. 

public static synchronized XAMSession createSessionCstri ng applicationVersionName) { 

// check that the application has supplied 

// some application names with content 

if (applicationVersionName == null 

II appl i cati onversi onName. equal s( )) { . ^ „, 

throw new XAMExceptionC'The ApplicationVersionName cannot be empty ); 

} 

// check if we al rady have a session created but without any 
// application names or we don't have a session yet. 
if (sessionlsNamed == true II latestsession == null) { 

// we already had a named session so create a new one for the new names 
// or we don't have a session yet. 
latestsession = createSessionObjectO ; 

} 

: a named session 

// now put the application names into the session. 
1 atestsessi on . setAppl i cati onName (appl i cati onversi onName) ; 
return latestsession; 



* Thi^Lth^ma^be'called'by'libraries that wish to use XAM but ; 

* part of the main application logic and cannot get to. the <code> 

* XAMSession</code> instance returned by the full version of this method. 

* If the full version is called once then all calls to this method 

* (before or after the full version) will return the same <code> 

* XAMSession</code> instance, if mutiple calls are made to the full 

* version then calls to this method will return the latest <code> 

* XAMSession</code> instance return from a full call. 

* At least one call must be made to the full version or no measurements 

* will be recorded. 

public static synchronized XAMSession createsessionO 
throws classNotFoundException { 
if (latestsession == null) { 

latestsession = createSessionObjectO; 

return latestsession; 

} 



* create an instance of XAMSession. 
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* The system property "XAM. implementation. class" is used 

* to get a class name which the method trys to load and 

* create and instance of. 

* ©return the newly created xam session. 

private static XAMSessionimpl createsessionObjectO { 
try { 

Class xamsessionclass = loadOfXAMltnplementationO ; 
XAMSessionimpl thesession = 

(XAMSessionlmpl)xamsessionClass.newlnstanceO ; 

// now check the the session can im'tialze itself 
// sucessfully 
thesessi on . i ni ti al ze () ; 

return thesession; 
} catch (Exception e) { 

// keep trying not to throw any exceptions from this method 
return new net. espeak. management. xam. noop . NoopSessi on O ; 

} 

} 



* return the name of the impl mentation class that we should load and use 

* ©return a fully qualified class name 

private static String implementationClassNameO { 

string implclass = System . getProperty (xam_implentation_property , 

D E F AU LT_XAM_IM P L EM E NT ATI ON_NAM E) ; 



/ * make sure the implementation is on the class path when this class is 

* loaded to avoid late failure due to the implementation not being on 

* the classpath. If class not found and the property 

* xam_loadfailexit_PROPERTY == 'true' the program will be halted 

* with <code>System.exit(l) ;</code> otherwise the noop implementation 

* will be returned. 

private static class loadofXAMlmplementationO { 

Class impletnentationclass = default_kam_implementation_class; 
try { 

// try to load the class in the system property. 
String i mpl ementati onName = implementationClassNameO; 

if (impl ementati onName == null) { 

// property not set so return noop class 
return default_j<am_implementation_class; 



■ -■ — ..ie(i mpl ementati onName) 

.„^^h(ClassNotFoundException e) { 
// failed to load the cl"" 



f ("true". equals (System. getProperty(XAM_LOADFAiLEXiT_PROPERTY, 
default_jxam_loadfailexit))) { 

should exit so rethrow exception 



} else { 

// just use the default. 

retu rn defau lt_xam_implementation_CLASS ; 

} 

// check that the class actually subclasses the impl class 
if (xAMSession. class. isAssignableFrom(XAMSessionlmpl .class) == 1 
i f ("true" . equal s(System. getProperty (XAM_LOADFAILEXIT_PROPEF 
DEFAuLT_JXAM_LOADFAILEXIT))) { . 

throw new classNotFoundException( The XAM i mpl emenetati t 
+ " must extend: " 

+ net . espeak . management . xam .XAMSessi on . cl ass . getNamf 

} else { 
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} catch (ClassNotFoundException e) { 

// a falure and the fail property set to false so exit. 
System. err. println("f ailed to load XAM implementation class: " 

+ implementationClassNameO) ; 
System.err.printlnC'XAM implementation class name is set in the system property 

+ implementationclassNameO) ; 
System . e r r . pri ntl n (e . tost ri ng () ) ; 
System. exit(l) ; 
return null ; 

return implementationclass; 



XAMSession ic 



/*$ld: XAMSession. java,v 1.1.2.3 2000/05/18 21:14:57 zs Exp $*/ 



' (c) Copyright 2000 Hewlett-Packard Company ; 

! This program is free software; you can redistribute it and/or modify it * 

• under the terms of the gnu Lesser General Public License as published by - 
1 the Free Software Foundation; either version 2.1 of the License, or * 

• (at your option) any later version. * 

• This program is distributed in the hope that it will be useful, but i 

• without any warranty; without even the implied warranty of merchantability 4 
•• or fitness for a particular purpose. See the gnu Lesser General Public * 
■ License for more details. * 



■ You should have received a copy of the gnu Les 

• along with this program; if not, write to the 

• inc., 675 Mass Ave, Cambridge, MA 02139, USA. 



it . espeak . management 



This is the central type regi sti 
point of view. Calls are made oi 
to create measurement type instances 



* ©author David Stephenson 

* ©version $Revision: 1.1.2.3 $ $Date: 2000/05/18 21:14:57 $ 
public interface XAMSession { 

/** 

* create a new transaction type. 

* ©param typeidentifier a unique name for the transaction 

* measurement type. 

* ©param variables an array of variable specifications 

* ©param group this transaction type is to be included in 

* some XAMGroup's. 

* May be null or empty. 

public abstract XAMTransactionType newTransactionType(String typelden- 
XAMVariableSpec variables []) throws XAMException; 



* create a new atomic type. 

* ©param typeidentifier a unique name for the atomic measurement type 

* ©param variables an array of variable specifications 
... „ . .... _ — _ atom -j c tvpe -j s t0 t> e included in some XAMGroup's. 



nicType newA' 
-iables[]) tl 
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* register a double callback object with the session. This will 

* cause the creation of a sample measurement. 

* @param valueName a unique name for this value. 

* @param variables an array of variable specifications 

* ©param callbackobject an object which must implement the 

* XAMDoublevalue interface. 

public abstract XAMPollType newPollMeasurementType(String typeldenti fi er , 
XAMVariableSpec variables[], 

XAMCall backlnterface callback) throws XAMException; 



* create a variable specification which can be used when calling the 

* methods above. 

* @param name the name of the variable, must be unqiue within a 

* measurement type. 

* ©param isKey set to true if the variable could be used to cut the 

* data but not be summed or thresholded. 

* ©param Alphabet the scope of possible values for the variable. 

* E.g for a string { "ready", "running", "stopped" } 

* or for a long or double a range spec { "11" , "12" , "15" , "32 . . 126" } 

* ©param unit A string describing the unit of the variable. E.g. 

* 'kilos', 'sessions', 'requests , 'seconds' 

* ©param description Can contain any string, might contain a URL 

* to a localization service. 

public abstract XAMVariableSpec createstringvariablespec(string name, 
boolean isKey, String [] alphabet, String unit, 
String description) throws XAMExcepti on ; 



* create a variable specification which can be used when calling the 

* methods above. 

* ©param name the name of the variable, must be unqiue within a 

* measurement type. 

* ©param isKey set to true if the variable could be used to cut the 

* data but not be summed or thresholded. 

* ©param Alphabet the scope of possible values for the variable. 

* E.g for a string { "ready", ''running", "stopped" } 

* or for a long or double a range spec { "11" , i '12" , "15" , "32 . . 126" } 

* ©param unit A string describing the unit of the variable. E.g. 

* 'kilos', 'sessions', "requests , 'seconds' 

* ©param description Can contain any string, might contain a URL 

* to a localization service. 

public abstract XAMVariableSpec createLongvariableSpec(String name, 
boolean isKey, String [] alphabet, String unit, 
String description) throws XAMException ; 



* create a variable specification which can be used when calling the 

* methods above. 

* ©param name the name of the variable, must be unqiue within a 

* measurement type. 

* ©param isKey set to true if the variable could be used to cut the 

* data but not be summed or thresholded. 

* ©param Alphabet the scope of possible values for the variable. 

* E.g for a string { "ready", running", "stopped" } 

* or for a long or double a range spec { "11" , "12" , "15", "32 . . 126" } 

* ©param unit A string describing the unit of the variable. E.g. 

* "kilos', 'sessions', 'requests , 'seconds' 

* ©param description Can contain any string, might contain a URL 

* to a localization service. 

public abstract XAMVariableSpec createDoubleVariableSpec(String name, 
String [] alphabet, String unit, 
String description) throws XAMException; 



* create a long variable specification which can be used when calling the 

* methods above. 

* ©param name the name of the variable, must be unqiue within a 
- measurement type. 

* ©param className one of "string", "long" or "double". 

* ©param isKey set to true if the variable could be used to cut the data 

* but not be summed or thresholded. 

* ©param description Can contain any string, might contain a URL to a 

* localization service. 
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public XAMVariableSpec createLongvariableSpecCstn'ng name, boolean isKey, 
String description) throws XAMException; 

^ * create a string variable specification which can be used when calling t 

* methods above. 

* ©param name the name of the variable, must be unqiue within a 

* ©param className one of "string", "long" or "double". 

* ©pararn i sKey set to true if the variable could be used to cut the data 

* but not be summed or thresholded. 

* ©param description Can contain any string, might contain a URL to a 

* localization service. 
*/ 



* create a double variable specification which can be used when calling the 

* methods above. 

* ©param name the name of the variable, must be unqiue within a 

* measurement type. 

* ©param className one of "string", "long" or "double". 

* ©param i sKey set to true if the variable could be used to cut the data 

* but not be summed or thresholded. 

* ©param description Can contain any string, might contain a URL to a 

* localization service. 

public XAMVariableSpec createDoublevariableSpec (string name, 
String description) throws XAMException ; 

// * can be used by the application to check if the <code>XAMSession</code> 

* implemenetation have recvied configuration information from the xam 

* service. An application may wait until this value is true inorder not 

* to loose any measurement data. Applications should not wait idenfiatly 

* for a true value as the XAM library may not find a xam service. 

public boolean configuredO; 

XAMMeasurementType. lava 



/*$ld: XAMMeasurementType. java,v 1.1.2.2 2000/05/08 01:04:13 ds Exp $*/ 



' (O Copyright 2000 Hewlett-Packard Company ; 

' This program is free software; you can redistribute it and/or modify it - 

; under the terms of the gnu Lesser General Public License as published by - 

< the Free Software Foundation; either version 2.1 of the License, or ; 

' (at your option) any later version. * 

' This program is distributed in the hope that it will be useful, but " ; 

1 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - 

or FITNESS FOR A particular PURPOSE. See the GNU Lesser General public * 

'' License for more details. * 

You should have received a copy of the GNU Lesser General Public License " J 

•' along with this program; if not, write to the Free software Foundation, * 

*■ inc., 675 Mass Ave, Cambridge, ma 02139, USA. - 



package net . espeak . management . xam ; 

' ' * The top level class for Measurement type hierarchy. 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.2 $ $Date: 2000/05/08 01:04:13 $ 
public interface XAMMeasurementType { 
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: type 

public void setDescription(Stri ng description); 

/ * return the String form of the correlator for this transaction type. 

* The correlator is a Unicode string of the 

* form "System identi fier ! system instance identifierlType 

* Identifier!" 

* May be passed by the application to 

* component application which could use it to correlate two Occurrences 

* ©return String form of correlator, 
public String getCorrelatorAsStri ngO ; 

XAMOccuranceTvpe.iava 



/*$ld: XAMOccurrenceType. java.v 1.1.2.1 2000/05/08 01:04:16 ds Exp $*/ 



(c) Copyright 2000 Hewlett-Packard company * 

■ This program is free software; you can redistribute it and/or modify it * 

'< under the terms of the GNU Lesser General Public License as published by ; 

• the Free software Foundation; either version 2.1 of the License, or - 

• (at your option) any later version. " 

• This program is distributed in the hope that it will be useful, but * 
without any warranty; without even the implied warranty of merchantability - 

• or FITNESS FOR A particular purpose. See the GNU Lesser General Public - 

• License for more details. " { 

a copy of the gnu Lesser General Public License ■ 

if not, write to the Free Software Foundation, " ; 
■idge, MA 02139, USA. 



package net . espeak . management . xam ; 



* This is an abstract interface no actual instances 

* of this inteface should exist. The two concrete subclasses of 

* are <code>XAMAtomicType</code> and <code>XAMTransacti onType</code> 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.1 $ $Date: 2000/05/08 01:04:16 $ 
public interface XAMOccurrenceType extends XAMMeasurementType { 

/ * if this measurement type is not currently required by the library 

* then the application could save time by not creating the value set. 

* This value may change at any time so MUST be checked on a case by 

* do not cache the return value from this method!! 

* ©return indication if the measurement type is being used by the library 
public boolean enabledC); 

7. XA MA torn icTvpe. iava 



/*$id: XAMAtornicType. java.v 1.1.2.2 2000/05/08 01:04:10 ds Exp $*/ 



' (c) Copyright 2000 Hewlett-Packard company 

•' This program is free software; you can redistribute it and/or modify it 
•- under the terms of the GNU Lesser General Public License as published by 
* the Free software Foundation; either version 2.1 of the License, or 
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* This program is distributed in the hope that it will be useful, but " ; 

* without any warranty; without even the implied warranty of merchantability - 

* or FITNESS FOR A PARTICULAR PURPOSE . See the GNU Lesser General Public " ; 

* License for more details. * 

* you should have received a copy of the gnu Lesser General Public License 
- along with this program; if not, write to the Free Software Foundation, 

*■ inc., 675 Mass Ave, Cambridge, MA 02139, USA. ' 



: . espeak. management . xam ; 



* One instance of this class should exist for every Atomic measurement 

* type registered by the application. Each time the application 

* wishes to record an instance of this measurement type the 

* <code>getinstance</code> method must be called to create 

* a new instance of a measurement. 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.2 S $Date: 2000/05/08 01:04:10 $ 
public interface XAMAtomicType extends XAMOccurrenceType { 



* indicate that the Atomic occurrence has happened. Each time the 

* application wishes to record an instance of this measurement 

* type the this method must be called to create a new instance 

* of a measurement. 

* ©return atomic measurement instance 
public XAMAtomi cinstance getinstanceQ ; 



XAMTransaction Type, iava 

ype.java.v 1.1.2.2 2000/05/08 01:04:18 ds Exp $*/ 



; CO Copyright 2000 Hewlett-Packard Company * 

•' This program is free software; you can redistribute it and/or modify it 4 

! under the terms of the GNU Lesser General Public License as published by " ; 

■■ the Free Software Foundation; either version 2.1 of the License, or * 

* Cat your option) any later version. * 

■ This program is distributed in the hope that it will be useful, but * 

t WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - 

•- or fitness for A particular purpose, see the gnu Lesser General Public > 

License for more details. * 



, Cambridge, ma 02139, USA. 



* One instance of this class should exist for every Transaction measurement 

* registered by the application. Each time the application 

* wishes to record an instance of this measurement type one of the 

* <code>beginO</code> methods must be called to create 

* a new instance of a transaction measurement. 
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* ©author David Stephenson 

* ©version $Revision: 1.1.2.2 $ $Date: 2000/05/08 01:04:18 $ 
public interface XAMTransactionType extends XAMOccurrenceType { 

^ * inform XAM that a new trans 
* ©return a new instance of transacts 

public XAMTransactioninstance beginQ; 



* inform XAM about a new transaction that started some time ago. 

* ©param time the time instant the transaction started. 

* ©return a new instance of transaction measurement. 

public XAMTransactioninstance began (XAMTi me time) throws XAMException; 



* inform XAM about a new transaction that started some time ago. 

* ©param time the time instant the transaction started. The value should 

* be in ISO 8601 format. Only time values generated from xam 

* libraries should be used here. 

* ©return a new instance of transaction measurement. 

public XAMTransactioninstance began (string time) throws XAMException; 



XAMOccurancelnstance. lava 

irrencelnstance. java.v 1.1.2.1 2000/05/08 01:04:15 ds 



' (c) Copyright 2000 Hewlett-Packard company 

' This program is free software; you can redistribute i 
■■ under the terms of the GNU Lesser General Public License ; 

• the Free Software Foundation; either version 2.1 of the Liwnic, ^ ( 

• Cat your option) any later version. t 

■ This program is distributed in the hope that it will be useful, but * 

• without any warranty; without even the implied warranty of merchantability ; 
•• or fitness for a particular purpose, see the gnu Lesser General Public 

• License for more details. \. 
■< you should have received a copy of the GNU Lesser General Public License 

• along with this program; if not, write to the Free Software Foundation, ; 
- inc., 675 Mass Ave, Cambridge, MA 02139, USA. 



:speak . management . x; 



' This is an abstract interface no actual instances 

• of this inteface should exist. The two concrete subclasses of 

' are <code>XAMAtomi cinstance</code> and <code>XAMTransacti onlnstance</code> 

' ©author David Stephenson 

' ©version $Revision: 1.1.2.1 $ $Date: 2000/05/08 01:04:15 $ 



* set the parent instance correlator. The correlator is a combination 

* system identifier, system instance identifier, Type 

* Identifier and Type Instance identifier. 

* ©param parentlnstance the instance identifier of the parent, 
public void setParentCorrelator(XAMOccurrenceinstance parentlnstance) 
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throws XAMException; 



f * set the parent instance correlator. The correlator is a Unicode strinc 
* of the form "system identi fi er ! system Instance identi fi er !Type 
' -' "fieriType Instance identifier" 

parentinstance the instance identifier of the parent in String 

public void setParentCorrel atorCstri ng parentcorrel ator) 
throws XAMException; 

} 

10. XAMTransactionlnstance lava 

/*$ld: XAMTransactionlnstance. java,v 1.1.2.2 2000/05/08 01:04:17 ds Exp $*/ 



* (c) copyright 2000 Hewlett-Packard company * 

* This program is free software; you can redistribute it and/or modify it * 

* under the terms of the GNU Lesser General Public License as published by - 

* the Free Software Foundation; either version 2.1 of the License, or ^ 
- (at your option) any later version. ^ 

* This program is distributed in the hope that it will be useful, but * 

* WITHOUT ANY warranty ; without even the implied warranty of merchantability - 
~- or fitness for A particular purpose. See the GNU Lesser General Public ; 

* License for more details. \ 

~ You should have received z 

* along with this program; i 

* inc., 675 Mass Ave, Cambridge, MA 02139, USA. 



* An instance of a Transaction measurement, instances are created from 

* a XAMTransactionType object, instances of this class can only be used 

* to report one measurement. Each time a new transaction measurement 

* occures a new instance of this class must be created. 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.2 $ $Date: 2000/05/08 01:04:17 $ 

public interface XAMTransactionlnstance extends XAMOccurrencelnstance { 

/ * indicate that the transactions has finished sucessfully the completed field 

* will be set to 'ok'. Measurement data will be generated for this instance. 

* All the variables that are defined for this measurement type need to be set 

* before calling this method. 



* indicate that the transactions has 

* will be set to 'fail'. Measurement 

* All the variables that are defined 

* before calling this method. 

public void abort Q; 



finished abnormally the completed field 
data will be generated for this instance, 
for this measurement type need to be set 



' indicate that the transaction should be ignored for measurement 
' purposes. This might be used in cases such as transaction rollback 
' or transaction failure, where a different measurement type should 
' now be used. Measurement data will NOT be generated for this mstanc 
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public XAMTime startTime(); 

^ * return the String form of the correlator for this transactic 

* The correlator is a Unicode string of the 

* form 'system identi fi er ! System instance identifierlType 

* Identifier ! Type instance Identifier' 

* May be passed by the application to 

* component application which could use it to correlate two 0< 

* ©return string form of correlator, 
public String getcorrelatorAsStringO ; 

XAMCallbacklnterface. iava 



r 1.1.2.3 2000/05/18 21:14:56 zs Exp $*/ 



- (c) copyright 2000 Hewlett-Packard Company * 

' This program is free software; you can redistribute it and/or modify it * 
' under the terms of the GNU Lesser General Public License as published by ; 
' the Free Software Foundation; either version 2.1 of the License, or ; 
; (at your option) any later version. 

s This program is distributed in the hope that it will be useful, but ' 
-' without any warranty; without even the implied warranty of merchantability • 

* or fitness FOR A particular purpose. See the gnu Lesser General public • 
■ License for more details. 

- you should have received a copy of the GNU Les 

* along with this program; if not, write to the 

* inc., 675 Mass Ave, Cambridge, ma 02159, USA. 



package net . espeak . management . xam ; 

^ * This is the Poll measurement callback inteface. Some applica 

* class must implement this inteface if the application regist 

* measurements. 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.3 $ $Date: 2000/05/18 21:14:56 $ 
public interface XAMCallbacklnterface { 



/** 



method is called by the xam library every time it wishes 1 
' the measurement. The application must make calls on the <code> 
' measurementinstance</code> object to post the measurement data. 
' References to the measurementlnstance object should not be kept after 

' the method returns. Runtime exceptions thrown from implei — 

' method will be treated as a return. 



public void requestingMeasurement(XAMPoll instance measurementlnstance); 

XAMAtomicInstance.iava 



/*$ld: XAMAtomiclnstance. java,v 1.1.2.2 2000/05/08 01:04:09 ds Exp $*/ 
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' (c) Copyright 2000 Hewlett-Packard company 

' This program is free software; you can redistribute it and/or modify it 
1 under the terms of the gnu Lesser General Public License as published by 
: the Free Software Foundation; either version 2.1 of the License, or 
■■ (at your option) any later version. 

' This proqram is distributed in the hope that it will be useful, but 
■ without any warranty; without even the implied warranty of merchantability 
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 

• License for more details. 

You should have received a copy of the GNU Lesser General Public License 

• along with this program; if not, write to the Free Software Foundation, 
•' inc., 675 Mass Ave, Cambridge, MA 02139, USA. 



t . espeak . management . xam ; 



n w, n ^w... .w i are created from 

•■ a XAMAtomi cType object, instances of this class can only be used 

• to report one measurement. Each time a new atomic measurement 
'< occures a new instance of this class must be created. 

• ©author David Stephenson 
i SRevision: 1.1.2.2 S $Date: 2000/05/08 01:04:09 $ 



--■ the value set data has been inserted, so the measurement library 

* can take the data. This method should be called once only per 

* object instance, if the method is called twice then an exception 

* will be thrown. 

public void reportO; 

XAMPollinzTvpe. iava 



/*$Id: XAMPollType.java.v 1.1.2.1 2000/05/18 21:19:18 zs Exp $*/ 



: (c) Copyright 2000 Hewlett-Packard company 

'* This program is free software; you can redistribute it and/or modify it 

■ under the terms of the GNU Lesser General Public License as published by 

* the Free Software Foundation; either version 2.1 of the License, or 

■ Cat your option) any later version. 

This program is distributed in the hope that it will be useful, but 

* without ANY warranty; without even the implied warranty of merchantability 
or fitness FOR A particular purpose . See the GNU Lesser General Public 

* License for more details. 

- You should have received a copy of the gnu Les: 

* along with this program; if not, write to the I 

* inc., 675 Mass Ave, Cambridge, ma 02139, USA. 



it . espeak . management . xam ; 



* One instance of this class should exist for every Poll measurement 

* registered by the application. 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.1 $ SDate: 2000/05/18 21:19:18 $ 
*/ 
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public interface XAMPollType extends XAMMeasurementType { 

)f the type which was registered by 
: the application gave to this Poll type. 

public String getTypeldenti fi er O ; 

XAMException iava 



/*$Id: XAMException. java.v 1.1.2.2 2000/05/08 01:04:11 ds Exp $*/ 



' (c) copyright 2000 Hewlett-Packard Company * 

■■ This program is free software; you can redistribute it and/or modify it * 

< under the terms of the GNU Lesser General public License as published by - 

' the Free Software Foundation; either version 2.1 of the License, or * 

' Cat your option) any later version. ' f 

• This program is distributed in the hope that it will be useful, but * 

* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - 
' or FITNESS FOR A PARTICULAR PURPOSE . See the GNU Lesser General Public • 
i License for more details. * 

• you should have received a copy of the gnu Lesser General public License - 
fr along with this program; if not, write to the Free software Foundation, > 

* inc., 675 Mass Ave, Cambridge, MA 02139, USA. 



package net . e speak. management . xam ; 

^* The XAM library passes all runtime errors as instatnces of this exception 

* Th^XAM library will only throw exception is the case of bad usage by the 

* if P the a xAM n iibrary sufferers an internal error or cannot reach the xam 

* service no exceptions will be thrown, if the application is programmed 

* correctly this exception will not be thrown. 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.2 $ $Date: 2000/05/08 01:04:11 $ 
public class XAMException extends RuntimeException { 

' '* create a xam Exception 

* Oparam msg 

public xam Exception (St ring msg) { 
super (msg); 



/*$Id: XAMClock.java.v 1.1.2.5 2000/05/18 21:14:59 zs Exp $*/ 

* (c) Copyright 2000 Hewlett-Packard company 

* This proqram is free software; you can redistribute it and/or modify it 

* under the terms of the GNU Lesser General Public License as published by 

* the Free Software Foundation; either version 2.1 of the License, or 

* (at your option) any later version. 

* This program is distributed in the hope that it will be useful, but 

* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 

* or fitness FOR A particular purpose, see the gnu Lesser General Public 

* License for more details. 
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< You should have received a copy of the gnu Lesser General public License 

< along with this program; if not, write to the Free Software Foundation, 
' inc., 675 Mass Ave, Cambridge, MA 02139, USA. 



package net . espeak . management . xam . cl ock ; 

import java. Tang. reflect.*; 

import java. text . si mpl eDateFormat ; 

i mport net . espeak . management . xam . XAMExcepti on ; 

^- This is class gives access to the most accurate time available. 

* The clock will use an implementation class as per the system property 

* ©author David Stephenson 

* ©version SRevision: 1.1.2.5 $ $Date: 2000/05/18 21:14:59 $ 
public class XAMClock { 

* the time now. 

* ©return the current time. 

public static XAMTime gerrimeO; 

^* the clock resolution in seconds, i.e the smallest measurable 

* difference in time that the clock can produce. 

* ©return the clock resolution time in seconds. 

public static double getClockResolutionO ; 

^ * create a XAMTime object from a string in ISO 8601 format. 

* ISO (international organization for Standardization). Representatio 

* of dates and times, 1988-06-15. 

* Available at; http://www.iso.ch/tnarkete/8601.pdt 

* ©return a string containing a time instant in the form 

* "cCYY-MM-DDThh;mm:ss.ssssss" or within me zone offset 

* eg "cCYY-MM-DDThh:mm:ss.ssssss+hh:mm" 

public static XAMTime getTimeFromString (String time); 



; create an instance of XAMSession. _ „ . , 

' The system property "xam. implementation, class is used 
; to get a class name which the method trys to load and 



* ©return the newly created XAM session, 
private static XAMClockimpl createClockO I 

/ *"check that the time string is in ISO 8601 format. 

* ISO (international Organisation for standardization). Representations 

* of dates and times, 1988-06-15. 

* Available at: http://wvwv.iso.ch/markete/8601.pdf 

* ©return a string containing a time instant in the form 

* ,, CCYY-MM-ddThh:mm:ss.ssssss" or with time zone offset 

* "cCYY-MM-ddThh:mm:ss.ssssss+hh:mm" or "cCYY-MM-ddThh:mm:ss.ssssss-nh. 

public static void checkTi me (String time); 



/*$ld: XAMTime.java,v 1.1.2.4 2000/05/18 21:14:59 zs Exp $*/ 
* (c) copyright 2000 Hewlett-Packard company 
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* This program is free software; you can redistribute it and/or modify it 

* under the terms of the GNU Lesser General Public License as published by 

* the Free Software Foundation; either version 2.1 of the License, or * 

* (at your option) any later version. * 

* This program is distributed in the hope that it will be useful, but " ; 

* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ■ 

* or fitness FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public • 

* You should have received a copy of the gnu Lesser 

* along with this program; if not, write to the Fre 

* inc., 675 Mass Ave, Cambridge, MA 02139, USA. 

*/ 

package net . espeak . management . xam . cl ock; 

^* This type is used by XAM to hold a time instant. There are no methods to 

* convert to/from java time formats. This is to discourage pollution of the 

* XAM time system from the java time system which may be different. 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.4 $ $Date: 2000/05/18 21:14:59 $ 
public interface XAMTime { 

/ '* return the time in ISO 8601 format. 

* ISO (international organization for standardization). Re 

* of dates and times, 1988-06-15. 

* Available at: http://www.iso.ch/markete/8601.pdf 

* ©return a string containing a time instant in the form 

* "CCYY-MM-ddThh:mm:ss.ssssss" or with time zone offset 

* "cCYY-MM-ddThh:mtn:ss.ssssss+hh:mm" or "CCYY-MM-ddThh:mm: 

String getlS0860lFormat() ; 

^ * calculate the difference between the two times in seconc 

* ©param time the other time value 
public double minus (XAMTi me time); 



* Generate a new time in the future 

* ©pararn time in seconds to be added 1 
public XAMTime plusCdouble time); 

XAMMeasurementlnstance. java 



rementlnstance . ja\ 



' 1.1.2.1 2000/05/08 01:04:13 ds Exp $*/ 



1 (c) copyright 2000 Hewlett-Packard Company * 

* This program is free software; you can redistribute it and/or modify it * 
•• under the terms of the GNU Lesser General Public License as published by * 
1 the Free software Foundation; either version 2.1 of the License, or - 
- Cat your option) any later version. ^ 

; - This program is distributed in the hope that it will be useful, but - 

* without any warranty; without even the implied warranty of merchantability 
" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 

* License for more details. 

* You should have received a copy of the gnu Lesser 

* along with this program; if not, write to the Fr« 

* inc., 675 Mass Ave, Cambridge, MA 02139, USA. 
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package net . espeak . management . xam ; 

^* Through this interface several variable values may be set by the application. 

* The correct method must be called depending on the class type specified in the 

* variable declaration. A value may be writen more than once if necessary. 

* ©author David Stephenson 

* ©version $Revision: 1.1.2.1 S $Date: 2000/05/08 01:04:13 $ 
public interface XAMMeasurementinstance { 

// * set a value of a variable. 

* @param name name of the variable. 

* @param value the value of the variable. 

public void setstri ngval ue (Stri ng name, String value) throws XAMExcepti on ; 



public void setLongval ue(stri ng name, long value) throws XAMExcepti oi 



* set a value of a variable. 

* ©param name name of the variable. 

* ©param value the value of the variable. 

public void setDoublevalueCstri ng name, double value) throws XAMException; 
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